Copyright: Copyright ® 1996 Progress Software Corporation


 Getting Started with the CIRAS Control

Related Topics

This topic introduces Remote Access Service (RAS) and its implementation as the Crescent Internet ToolPak RAS Control (CIRAS). You can access these topics:

What RAS is

What the CIRAS control is

Using the CIRAS control

The last topic, Using the CIRAS control, describes the properties, methods and events that you use when performing a simple RAS connection.


 What is RAS?

Related Topics

The RAS (Remote Access Service) protocol provides dial-in access to printer and disk resources.


 What is the CIRAS Control?

Related Topics

The Crescent Internet ToolPak RAS (CIRAS) control provides programmatic dial-up access to a network via SLIP, PPP, or RAS proprietary protocol. This enables you to build Internet applications without the need for an external dialer.

CIRAS has a simple programming interface in which you set property values and call methods to perform the desired tasks. When the method completes, the control updates properties and fires events as necessary.


 Programming Tasks

Related Topics

This topic describes how to write a simple module that connects a Visual Basic application to a RAS server.

Follow these steps to connect to a RAS server:

1. Set these properties:
HostName
EntryName (or Phonenumber)
UserName
Password

2. Call the RASDial method.

3. When the RASConnectionStatus event fires and the state& parameter equals 23 (the value associated with the connected state), the RASDial method succeeded. (The states are defined in the RASStatus.BAS file.)

Heres a code sample:

Form_Load
CIRAS1.HostName = myhost
CIRAS1.EntryName = devserver
UserName = myuser
Password = mypass

CIRAS_ConnectionStatus()

The status changes as the connection progresses


Getting Started with the CIRAS Control
What is RAS?
What is the CIRAS Control?
Programming Tasks


What is RAS?
What is the CIRAS Control?
Programming Tasks
The Crescent Internet ToolPak RAS Control Reference


Getting Started with the CIRAS Control
What is the CIRAS Control?
Programming Tasks
The Crescent Internet ToolPak RAS Control Reference


Getting Started with the CIRAS Control
What is RAS?
Programming Tasks
The Crescent Internet ToolPak RAS Control Reference


Getting Started with the CIRAS Control
What is RAS?
What is the CIRAS Control?
The Crescent Internet ToolPak RAS Control Reference


 The Crescent Internet ToolPak RAS Control

Related Topics

Control File

CIRAS.OCX

Object Type

CIRAS

Purpose

The Crescent Internet ToolPak RAS (CIRAS) control provides Visual Basic applications with programmatic dial-up access to a network via SLIP, PPP, or the RAS (Remote Access Services) proprietary protocol. This enables you to build Internet applications without the need for an external dialer.

Properties

AboutBox	Container	DeviceName c
DeviceType c	Domain c	DragIcon
DragMode	EntryName c	Handle c
Height	HostName c	Index
Left	ListBoxName c	Name
Object	Parent	Password  c
Phonebook  c	PhoneNumber  c	ShowWhatsThis
Tag	Timeout  c	Top
UserName  c	Visible	WhatsThisHelpID
Width


Events

DragDrop	DragOver	FoundHost c
RASConnectionStatus c
Methods

HostAvailablec	RASDial c	RASEnumConnectionsc
RASEnumEntriesc	RASGetConnectStatusc	RASHangUpc
c A custom or modified property, method, or event.


 DeviceName Property

Applies To

CIRAS

Purpose

The DeviceName property returns the name of the device used by the current RAS connection.

Syntax

[string$] = [Form.]CIRAS.DeviceName

Data Type

String

Usage

Read only at runtime.

Comments

The RASGetConnectStatus method sets the DeviceName property.

Since you can have multiple RAS connections in a single session, make sure that you set the Handle property to the RAS connection for which you want status information before you call the RASGetConnectStatus method.

See Also

Handle, RASGetConnectStatus


 DeviceType Property

Applies To

CIRAS

Purpose

The DeviceType property returns the type of device used by the current RAS connection.

Syntax

[string$] = [Form.]CIRAS.DeviceType

Data Type

String

Usage

Read only at runtime.

Comments

The RASGetConnectStatus methods sets the DeviceType property.

Since you can have multiple RAS connections in a single session, make sure that you set the Handle property to the RAS connections for which you want status information before you call the RASGetConnectStatus method.

See Also

RASGetConnectStatus


 Domain Property

Applies To

CIRAS

Purpose

The Domain property sets or returns the fully qualified domain name to be used by the next connection.

Syntax

[Form.]CIRAS.Domain = [string$]

Data Type

String

Usage

Read/Write

Comments

Set the Domain property before calling the RASDial method.

See Also

RASDial


 EntryName Property

Applies To

CIRAS

Purpose

The EntryName property returns a saved RAS phonebook entry that will be used by the next RAS connection attempt.

Syntax

[Form.]CIRAS.EntryName = [string$]

Data Type

String

Usage

Read/Write at runtime.

Comments

Set the EntryName property before calling the RASDial method .

When the EntryName property and the PhoneNumber property both contain values, the EntryName property takes precedence.

The EntryName can be an entry found in the RAS phonebook.

See Also

EntryName, RASDial


 Handle Property

Applies To

CIRAS

Purpose

The Handle property returns a new handle (for an in-use port after each RASDial method call.

Syntax

[long&] = [Form.]CIRAS.Handle

Data Type

Long

Usage

Read only at runtime.

Comments

You use the Handle property to maintain information about a specific connection. Each time you call the RASDial method, it updates the Handle property. If you plan to have mutiple connections in a given session, you must store the Handle property in another variable, or it will be overwritten with a new Handle value each time you call the RASDial method.

Both RASHangUp and RASGetConnectStatus use the Handle to determine which connection to terminate or to deliver the status for.

See Also

RASDial, RASGetConnectStatus, RASHangUp


 HostName Property

Applies To

CIRAS

Purpose

The HostName property sets or returns the name of the network host the HostAvailable method tries to locate.

Syntax

[Form.]CIRAS.HostName = [string$]

Data Type

String

Usage

Read/Write at runtime and designtime.

Comments

Set the HostName property before calling the HostAvailable method. HostAvailable searches the reachable network to attempt to find the computer represented by HostName. An example of a HostName is www.progress.com.

See Also

HostAvailable


 ListBoxName Property

Applies To

CIRAS

Purpose

The ListBoxName property specifies the name of an existing listbox object that will be populated by the items returned by the RASEnumEntries method or RASEnumConnections method.

Syntax

Set CIRAS.ListBoxName = Entries

Data Type

Object

Usage

Write only at runtime.

Comments

If you want CIRAS to populate a listbox then set the ListBoxName property before calling the RASEnumEntries or RASEnumConnections methods. The CIRAS control updates the Listbox object when the RASEnumEntries method finds phonebook entries or RASEnumConnections method finds active connections.

The data returned by RASEnumEntries and RASEnumConnections is discarded if there is no value in the ListBoxName property. Note that RASEnumEntries and RASEnumConnections clears any data in the named ListBox object, so if you want to view the data returned by these methods concurrently, you must create two separate ListBox objects.

See Also

RASEnumEntries, RASEnumConnections


 Password Property

Applies To

CIRAS

Purpose

The Password property contains the password for the user that the next connection attempt will use.

Syntax

CIRAS.Password = strPassword$

Data Type

String

Usage

Read/Write at designtime and runtime.

Comments

Set the Username and Password properties before calling the RASDial method. The username and password must be valid for the host (HostName property) to which RAS is attempting to connect.

See Also

HostName, RASDial, Username


 Phonebook Property

Applies To

CIRAS

Purpose

The Phonebook property contains the fully qualified path of the RAS phonebook.

Syntax

CIRAS.Phonebook = strPhonebook$

Data Type

String

Usage

Read/Write at designtime and runtime.

Comments

Set the Phonebook property before calling the RASDial method. An example of a Phonebook property entry is C:\WINNT35\SYSTEM32\DRIVERS\ETC\PRGS.PBK.

This property is not applicable under WIN95 because the RAS phonebook is stored in the registry.

See Also

RASDial


 PhoneNumber Property

Applies To

CIRAS

Purpose

The PhoneNumber property contains the phone number that will be used by the next RAS connection attempt. You can use the PhoneNumber property instead of a RAS phonebook entry.

Syntax

CIRAS.PhoneNumber = strPhoneNumber$

Data Type

String

Usage

Read/Write at runtime.

Comments

Set the PhoneNumber property before calling the RASDial method. It can contain formatting characters, for example, 1, 555-1212.

When the EntryName property and the PhoneNumber property both contain values, the EntryName property takes precedence.

See Also

EntryName, RASDial


 Timeout Property

Applies To

CIRAS

Purpose

The Timeout property sets a value that specifies the amount of time (in milliseconds) that the HostAvailable method waits before firing the FoundHost event when the host specified in HostName is not found.

Syntax

CIRAS.Timeout = nTimeout&

Data Type

Long

Usage

Read/Write at designtime and runtime.

Comments

Set the Timeout property before calling the HostAvailable method. The default is 5,000 ms. To set the Timeout to 32 seconds, you would provide a value of 32000.

If the HostAvailable method does not find the host specified by the HostName property during the specified Timeout period, the FoundHost event fires, but the data returned to the FoundHost reply$ parameter is NULL. If the HostAvailable finds the host during the Timeout period, the FoundHost event fires and the reply$ parameter contains information about the host. The reply$ is formatted like a string returned by PING. It has this format: Internet Address, Round Trip Time (ms), Time To Live (sec). Where:

Internet Address	the HostAddress associated with the HostName property.
Round Trip Time	the total time (in milliseconds) needed for the packet to go from your machine to the host machine and back.
Time To Live	the time in seconds that the packet will exist without finding its destination before the packet is discarded.
See Also

FoundHost, HostAvailable, HostName


 UserName Property

Applies To

CIRAS

Purpose

The username property contains the user name that the next connection attempt will use.

Syntax

CIRAS.UserName = strUserName$

Data Type

String

Usage

Read/Write at designtime and runtime.

Comments

Set the Username and Password properties before calling the RASDial method. The username and password must be valid for the host (HostName property) to which RAS is attempting to connect.

See Also

HostName, RASDial, Username


 FoundHost Event

Applies To

CIRAS

Purpose

The FoundHost event notifies CIRAS when either the HostAvailable method has timed-out or a valid host has been found.

Syntax

CIRAS1_FoundHost(ByVal HostName As String, ByVal reply As String)

Comments

When you call the RASDial method, CIRAS sets a timer (based on the value of the Timeout property). The FoundHost event fires when the HostAvailable method has timed-out or when HostAvailable has found the named host (HostName property).

If the HostAvailable method does not find the host specified by the HostName property during the specified Timeout period, the FoundHost event fires, but the data returned to the FoundHost reply$ parameter is NULL. If the HostAvailable finds the host during the Timeout period, the FoundHost event fires and the reply$ parameter contains information about the host. The reply$ is formatted like a string returned by PING.

It has this format: Internet Address, Round Trip Time (ms), Time To Live (sec). Where:

Internet Address	the HostAddress associated with the HostName property.
Round Trip Time	the total time (in milliseconds) needed for the packet to go from your machine to the host machine and back.
Time To Live	the time in seconds that the packet will exist without finding its destination before the packet is discarded.
See Also

HostAvailable, HostName, RASDial, Timeout


 RASConnectionStatus Event

Applies To

CIRAS

Purpose

The RASConnectionStatus event notifies CIRAS of the current status of a connection in progress.

Syntax

CIRAS_RASConnectionStatus(ByVal state As Long, ByVal error As Long)

Comments

The RASConnectStatus event fires when either the RASDial or RASGetConnectStatus methods are called. This event can be fired many times for the RASDial method because it fires each time the state of the connection changes.

See the RASStatus.BAS file for a complete enumeration of the state values that can occur when the RASDial method is called. See the RASError.BAS file for a complete enumeration of all error values that can occur.

See Also

RASDial, RASGetConnectStatus, RASError.BAS, RASStatus.BAS


 HostAvailable Method

Applies To

CIRAS

Purpose

The HostAvailable method determines if a host is accessible to the Visual Basic application.

Syntax

nTaskHandle& = CIRAS.HostAvailable

Data Type

Long

Comments

Use HostAvailable to determine if a host is available. The host can be available either through a RAS connection or a network connection. Set the HostName property before calling the HostAvailable method. The HostAvailable method is useful for applications that are used by people that are sometimes directly connected to a network, and sometimes are remotely connected to a network.

If you code your applications to use the HostAvailable method, you can prevent the application from attempting a RAS connection when the user is directly connected to the network.

See Also

FoundHost, RASDial


 RASDial Method

Applies To

CIRAS

Purpose

The RASDial method establishes a connection with a remote network or a standalone computer.

Syntax

nStatus& = CIRAS.RASDial

Data Type

Long

Comments

Set the HostName, EntryName (or Phonenumber), UserName and Password properties before calling the RASDial method.

The RASConnectionStatus event fires many times throughout the connection process as each stage is encountered. See RASError.BAS and RASStatus.BAS for a complete enumeration of all error and status messages.

See Also

RASConnectionStatus, RASError.BAS, RASStatus.BAS


 RASEnumConnections Method

Applies To

CIRAS

Purpose

The RASEnumConnections method returns all currently active RAS connections.

Syntax

nStatus& = CIRAS.EnumConnections

Data Type

Long

Comments

Set the ListBoxName property before calling the RASEnumConnections method if you want CIRAS to display a listing of the currently active connections in a ListBox object.

See Also

ListBoxName


 RASEnumEntries Method

Applies To

CIRAS

Purpose

This method returns all RAS phone book entries.

Syntax

nStatus& = CIRAS.EnumEntries

Data Type

Long

Comments

Set the ListBoxName property before calling the RASEnumEntries method if you want CIRAS to display the phone book entries in a ListBox object.

See Also

ListBoxName


 RASGetConnectStatus Method

Applies To

CIRAS

Purpose

The RASGetConnectStatus returns the current status of a connection in progress.

Syntax

nStatus& = CIRAS.RASGetConnectStatus

Data Type

Long

Comments

The RASGetConnectStatus method updates the DeviceName and DeviceType properties if a connection is in progress.

See RASError.BAS and RASStatus.BAS for a complete enumeration of all error and status messages.

See Also

DeviceName, DeviceType, RASError.BAS, RASStatus.BAS


 RASHangUp Method

Applies To

CIRAS

Purpose

The RASHangUp method disconnects and frees the port and its associated handle for the specified RAS handle.

Syntax

nStatus& = CIRAS.HangUp

Data Type

Long

Comments

You use the Handle property to maintain information about a specific connection. Each time you call the RASDial method, it updates the Handle property. If you plan to have mutiple connections in a given session, you must store the Handle property in another variable, or it will be overwritten with a new Handle value each time you call the RASDial method.

Both RASHangUp and RASGetConnectStatus use the Handle to determine which connection to terminate or to deliver the status for.

See Also

Handle


 General Tab

Applies To

CIRAS

This custom tab lets you set these custom properties:

Domain

EntryName

HostName

Password

PhoneBook

PhoneNumber

Timeout

UserName